It's helpful to describe the reason rather than state rules. We can link+summarize the javadoc (which is actually a super interesting -- if you're into that sort of thing -- detail):

https://docs.oracle.com/en/java/javase/17/docs/api//java.base/java/lang/reflect/InvocationTargetException.html#getTargetException()

This method predates the general-purpose exception chaining facility. The Throwable.getCause() method is now the preferred means of obtaining this information.

Makes sense, will update.

I was deciding between adding more detail (like the API note from the javadoc) or being super concise. Decided on being concise because I thought a dev would just want the fastest resolution, and wouldn't think too much about the difference.

But you're right. Since we have a suggested fix anyway, they will know how to change their code, and we can use the summary to provide context. For times we don't have a suggested fix, maybe we'd favor conciseness over context.

Oh. I have also missed updating the README for this check, and the collections.size() == 0 check... will update.

I haven't been updating hte readme lately -- imo we should codegen the list of checks and use the summary from annotations, but it's not high enough on my list to implement at the moment!

edit: posted this before I read your latest comment.

Also, what are your thoughts on moving the giant list of checks out of the main README, and into a separate md file? Each check can be a heading, so we could link directly to the check in the link argument of the BugPattern, and add as much detail as we'd like.

I like it

cool. Made a task in the backlog.